Text Provider

Plain text file implementation for UTCP

The Text provider enables UTCP to interact with tools defined in local text files, which is useful for file-based tools, development environments, and creating aggregated collections of tools from different providers without requiring a server component.

Configuration

Text providers are configured using the following JSON structure:

{
  "name": "local_tools",
  "provider_type": "text",
  "file_path": "/path/to/tools.json",
  "encoding": "utf-8",
  "watch_file": true,
  "cache_duration": 300000,
  "auto_reload": true
}

Configuration Fields

Field	Required	Description
`name`	Yes	Unique identifier for the provider
`provider_type`	Yes	Must be set to `"text"`
`file_path`	Yes	Path to the file containing tool definitions (supports absolute and relative paths)
`encoding`	No	File encoding (default: `"utf-8"`)
`watch_file`	No	Whether to watch the file for changes (default: `false`)
`cache_duration`	No	Cache duration in milliseconds (default: `300000`)
`auto_reload`	No	Whether to automatically reload when file changes (default: `true`)

Use Cases

The Text provider can be used in several scenarios:

File-Based Tools

Tools that operate on files or require local file system access. The tool definitions include information about how to delegate calls to local processes or file operations.

Tool Aggregation

Collecting tools from multiple providers into a single configuration file for easier management and deployment. Each tool can reference its own provider configuration.

Development & Testing

Creating mock tools for development and testing purposes without requiring actual service endpoints. Useful for prototyping and local development.

Configuration Management

Managing tool definitions as code, allowing version control and deployment automation of tool configurations across environments.

File Format

The text file should contain either:

UTCPManual Object

A complete UTCP manual containing version and tools array:

{
  "version": "1.0",
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "inputs": { ... },
      "outputs": { ... }
    }
  ]
}

Tools Array

A simple array of tool definitions:

[
  {
    "name": "tool_name",
    "description": "Tool description",
    "inputs": { ... },
    "outputs": { ... }
  }
]

Examples

Local System Tools

{
  "name": "local_file_tools",
  "provider_type": "text",
  "file_path": "/etc/utcp/system_tools.json",
  "watch_file": true,
  "auto_reload": true
}

Content of system_tools.json:

{
  "version": "1.0",
  "tools": [
    {
      "name": "read_system_stats",
      "description": "Read system statistics",
      "inputs": {
        "type": "object",
        "properties": {
          "stat_type": {
            "type": "string",
            "enum": ["cpu", "memory", "disk"],
            "description": "Type of statistics to read"
          }
        },
        "required": ["stat_type"]
      },
      "outputs": {
        "type": "object",
        "properties": {
          "usage_percent": {
            "type": "number",
            "description": "Usage percentage"
          },
          "details": {
            "type": "object",
            "description": "Detailed statistics"
          }
        }
      },
      "provider": {
        "name": "system",
        "provider_type": "cli",
        "command_name": "system-stats",
        "param_style": "named",
        "output_format": "json"
      }
    }
  ]
}

Aggregated Tool Collection

{
  "name": "tool_collection",
  "provider_type": "text",
  "file_path": "./config/aggregated_tools.json",
  "cache_duration": 600000
}

Content of aggregated_tools.json:

{
  "version": "1.0",
  "tools": [
    {
      "name": "weather",
      "description": "Get weather information",
      "inputs": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "Location to get weather for"
          }
        },
        "required": ["location"]
      },
      "outputs": {
        "type": "object",
        "properties": {
          "temperature": { "type": "number" },
          "conditions": { "type": "string" }
        }
      },
      "provider": {
        "name": "weather_api",
        "provider_type": "http",
        "url": "https://api.weather.com/current",
        "http_method": "GET",
        "auth": {
          "auth_type": "api_key",
          "api_key": "YOUR_WEATHER_KEY",
          "var_name": "X-API-Key"
        }
      }
    },
    {
      "name": "translate",
      "description": "Translate text between languages",
      "inputs": {
        "type": "object",
        "properties": {
          "text": { "type": "string" },
          "from_lang": { "type": "string" },
          "to_lang": { "type": "string" }
        },
        "required": ["text", "to_lang"]
      },
      "outputs": {
        "type": "object",
        "properties": {
          "translated_text": { "type": "string" }
        }
      },
      "provider": {
        "name": "translation_service",
        "provider_type": "graphql",
        "url": "https://api.translate.com/graphql",
        "operation_type": "mutation",
        "operation_name": "Translate"
      }
    }
  ]
}

Development Mock Tools

{
  "name": "dev_tools",
  "provider_type": "text",
  "file_path": "~/dev/utcp/mock_tools.json",
  "watch_file": true,
  "encoding": "utf-8"
}

File Operations

Reading

• Supports absolute and relative paths
• Automatic encoding detection when possible
• Caching for performance optimization

Watching

• File system monitoring for changes
• Automatic reloading when files are modified
• Graceful handling of file access errors

Best Practices

File Management

• Use version control for tool definition files
• Implement proper file permissions and access controls
• Consider using environment variables for sensitive data

Performance

• Use appropriate cache durations for file content
• Enable file watching only when necessary
• Validate JSON structure before processing

Error Handling

• Handle file not found errors gracefully
• Implement JSON parsing error recovery
• Log file access and parsing issues

Security

• Validate file paths to prevent directory traversal
• Use secure file permissions
• Consider encryption for sensitive tool definitions